Changing Your Part's Content (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 7 - Storage

Changing Your Part's Content
Users can change the content of your part through a variety of standard editing actions involving keyboard input, menu commands, scripting, and so on. How you can support those tasks on the Mac OS platform is described throughout this book, with additional information in Inside Macintosh and other programming texts.
This section summarizes the content-changing tasks of adding and removing embedded parts, and it notes the ways in which you must keep OpenDoc and other parts informed when you make content changes of any kind.

Adding an Embedded Part
Embedding is a process that can combine elements of storage, layout, data transfer, menu handling, and control manipulation. This section summarizes the embedding process; the summary is presented in this chapter because embedding involves such a fundamental change to a part's storage configuration.
In terms of the stored persistent objects involved, embedding breaks down to these basic alternatives:

Your part embeds either a new or preexisting frame into its content.
The embedded frame displays the content of either a new or preexisting part.

You create a new frame to embed by calling your draft's CreateFrame method; you obtain an existing frame to embed by calling your draft's AcquireFrame method. In situations where you must explicitly instantiate the part object to embed, you create a new part by calling your draft's CreatePart method, or you obtain an existing part by calling your draft's AcquirePart method.
Detailed procedures for embedding a part within your part are described in the sections "Pasting From the Clipboard". See those sections for more information. In summary, however, you perform these tasks when you embed:

You decide, based on your own part's content model and on information accompanying the transferred data, what area to give to the embedded part for display.

You retrieve or define a frame shape for the embedded frame. (The part to be embedded may or may not arrive with a suggested frame or frame shape.)
You decide where to position the embedded frame in your part's content; based on that position, you eventually create an external transform to use for positioning the facets of the embedded frame.

For each of your own part's display frames that is to show the embedded part, you create or retrieve a part object (if necessary), and then you create or retrieve a frame object.

If the part you are embedding is already attached to a frame, ignore this step. If not, you must manipulate the part itself. Either retrieve the part object (as when embedding pasted content that has no preexisting frame or adding a new frame to an existing embedded part) or create a new part object (as when creating a new part from a palette).
The embedded part is stored in your part's draft, but not in your part itself.
Either retrieve the supplied frame object (as when embedding pasted content that comes with a display frame) or create a new frame object (as when adding a new frame to an existing embedded part or creating a new part from a palette). If you retrieved or created a part the previous step, attach that part to the frame.
You store a reference to the frame somewhere in your part's content. The frame object itself is stored in your part's draft, but not in your part.

If the embedded part's frame is presently visible, you create a new facet (or facets) to display the embedded part.
As necessary or appropriate, you perform other tasks related to embedding, such as those described in the section "Working With Embedded Frames and Facets"

Removing an Embedded Part
To remove an embedded part from your part, you must remove all the facets of the part's display frame (your embedded frame), release or remove the embedded frame, and redisplay your own part's content. Follow the instructions in "Removing an Embedded Frame".
This procedure illustrates the fact that your part is not actually concerned with removing embedded parts themselves. Under user instruction or for other reasons, your part may have reason to remove one or more embedded frames; once the last display frame of a given embedded part is removed from your part, that part is no longer embedded in your part.

Making Content Changes Known
Whenever you make any significant change to your part's content, whether it involves adding, deleting, moving, or otherwise modifying your intrinsic content or your embedded frames, you must make those changes known to OpenDoc and to all containing parts of your part.

Call your draft's SetChangedFromPrev method. This call marks the draft as dirty, giving your part the opportunity to write itself to storage when the draft is closed.
Call the ContentUpdated method of each of your part's display frames in which the change occurred, passing it an identifying update ID, obtained in one of three ways:

returned from a call to the session object's UniqueUpdateID method (if the content change originated in your part's intrinsic content)
propagated from a link destination (see "Link Update ID")
propagated from a call to your EmbeddedFrameUpdated method (see "The EmbeddedFrameUpdated Method of Your Part Editor")
Calling ContentUpdated notifies your containing parts--and their containing parts, and so on--that your content has changed. The notification is necessary to allow all containing parts to update any link sources that they maintain.

You should call these methods as soon as is appropriate after making any content changes. You may not have to make the calls immediately after every minor change; it may be more efficient to wait for a pause in user input, for example, or until the active frame changes.
In addition to sending these notifications, you must of course also update your part's display if appropriate. This updating may involve adding or removing facets, adjusting intrinsic content, and invalidating areas that need to be redrawn.